[Experimental] Create a new folder

[Experimental] Create a new folder

cURL

curl --request POST \
  --url http://10.2.4.166:8080/composer/api/folders \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/vnd.composer.v3+json' \
  --header 'X-Enable-Preview: <x-enable-preview>' \
  --data '
{
  "folder_name": "My Folder",
  "description": "This folder contains dashboards",
  "parent_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "inheritance_state": "INHERIT",
  "content_type": "DASHBOARDS"
}
'

201

{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "parent_id": "<string>",
  "materialized_path": "<string>",
  "project_id": "<string>",
  "project_type": "DEFAULT",
  "permissions": [
    "READ"
  ],
  "visibility": "PRIVATE",
  "inheritance_state": "INHERIT",
  "folder_type": "CONNECTIONS",
  "content_type": "DASHBOARDS"
}

Authorizations

Authorization · string · header · required

HTTP Basic authentication using global administrator credentials (username and password).

Headers

X-Enable-Preview · string · default: true · required

Opt-in header required to access this experimental endpoint. Must be "true" (case-insensitive).

Body

application/vnd.composer.v3+json

Request object for creating a new folder

folder_name · string · required

The name of the folder

Maximum string length: 100

Example:

"My Folder"

description · string

Optional description of the folder

Maximum string length: 250

Example:

"This folder contains dashboards"

parent_id · string

The id of the parent folder; omit to create a root-level folder

Example:

"a1b2c3d4-0000-0000-0000-000000000000"

inheritance_state · enum<string>

ACL inheritance mode for the new folder; defaults to INHERIT when omitted

Available options: INHERIT, EXPLICIT

Example:

"INHERIT"

content_type · enum<string>

The library this folder organizes (DASHBOARDS or REPORTS). Required when parent_id is omitted (a root-level folder); ignored when parent_id is set — a child folder always inherits its parent's value

Available options: DASHBOARDS, REPORTS

Example:

"DASHBOARDS"

Response

201 - application/vnd.composer.v3+json

Created

Response object describing a newly created folder

id · string

The unique identifier of the created folder

name · string

The name of the created folder

description · string

The folder's description; null when none was ever set

parent_id · string

The id of the parent folder; null means this is a root folder

materialized_path · string

Full path from root; null for legacy folders not yet backfilled

project_id · string

The identifier of the project that owns the folder

project_type · enum<string>

The type of the owning project

Available options: DEFAULT, GLOBAL, CUSTOM, PERSONAL, LIBRARY_CUSTOM

permissions · enum<string>[]

The caller's own effective permissions on this folder, as an array of FolderAclBit names (READ, WRITE, CREATE, DELETE, ADMINISTER, OWNER), e.g. ["READ","WRITE"]. Computed per caller at request time, so it reflects real access: the creator of a root folder is its owner and sees all six, while a subfolder resolves to whatever the caller holds on the governing ancestor. Matches what a permissions query for the same folder and caller returns.

Available options: READ, WRITE, CREATE, DELETE, ADMINISTER, OWNER

visibility · enum<string>

The folder's visibility

Available options: PRIVATE, CUSTOM

inheritance_state · enum<string>

The folder's ACL inheritance state

Available options: INHERIT, EXPLICIT

folder_type · enum<string>

The type of the folder

Available options: CONNECTIONS, SOURCES, VISUALS, DASHBOARDS, REPORTS, PRIVATE, CUSTOM

content_type · enum<string>

The library this folder organizes (DASHBOARDS or REPORTS), resolved by the server; null when untagged

Available options: DASHBOARDS, REPORTS